<!DOCTYPE html>
            
<HTML>
<HEAD>
<meta name="booktitle" content="Developing Applications With Objective Caml" >
 <meta charset="ISO-8859-1"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0">
<META name="GENERATOR" content="hevea 1.05-7 of 2000-02-24">
<META NAME="Author" CONTENT="Christian.Queinnec@lip6.fr">
<LINK rel=stylesheet type="text/css" href="videoc-ocda.css">
<script language="JavaScript" src="videoc.js"><!--
//--></script>
<TITLE>
 Module Gc
</TITLE>
</HEAD>
<BODY class="regularBody">
<A HREF="book-ora087.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="book-ora089.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2> Module <TT>Gc</TT></H2>
<A NAME="@fonctions325"></A>
<A NAME="@fonctions326"></A>
<A NAME="@fonctions327"></A>
<A NAME="@fonctions328"></A>
<A NAME="@fonctions329"></A>
The <TT>Gc</TT> module lets one obtain statistics about the heap and
gives control over its evolution as well as allowing the activation of
various garbage collector phases. Two concrete record types are
defined: <I>stat</I> and <I>control</I>. The fields of type
<I>control</I> are modifiable; whereas those of <I>stat</I> are
not. The latter simply reflect the state of the heap at a given moment.<BR>
<BR>
The fields of a <I>stat</I> mainly contain counters indicating:
<UL>
<LI>
 the number of garbage collections: <TT>minor_collections</TT>,
 <TT>major_collections</TT> and <TT>compactions</TT>;

<LI> the number of words allocated and transfered since the beginning
 of the program: <TT>minor_words</TT>,
<TT>promoted_words</TT>, and <TT>major_words</TT>.
</UL>The fields of the record <I>control</I> are:
<UL>
<LI>
 <TT>minor_heap_size</TT>, which defines the size of the zone
 allotted to the younger generation;

<LI> <TT>major_heap_increment</TT>, which defines the increment
 applied to the growth of the region for the older generation;

<LI> <TT>space_overhead</TT>, which defines the percentage of the
 memory used beyond which a major garbage collection is begun
 (the default value is 42);

<LI> <TT>max_overhead</TT>, which defines the connection between free
 memory and occupied memory after which compactification is activated.
 A value of 0 causes a systematic compactification after every major
 garbage collection. The maximal value of 1000000 inhibits
 compactification. 

<LI> <TT>verbose</TT> is an integer parameter governing the tracing of
 the activities of the garbage collector.
</UL>
Functions manipulating the types <I>stat</I> and <I>control</I>
are given in figure <A HREF="book-ora088.html#fig-statctrl">9.13</A>.
<BLOCKQUOTE><DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV>
<DIV ALIGN=center>
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD  ALIGN=left NOWRAP><TT>stat</TT></TD>
<TD  ALIGN=left NOWRAP><I>unit </I><I>-&gt;</I><I> stat</I></TD>
</TR>
<TR><TD  ALIGN=left NOWRAP><TT>print_stat</TT></TD>
<TD  ALIGN=left NOWRAP><I>out_channel </I><I>-&gt;</I><I> unit</I></TD>
</TR>
<TR><TD  ALIGN=left NOWRAP><TT>get</TT></TD>
<TD  ALIGN=left NOWRAP><I>unit </I><I><FONT FACE=symbol>�</FONT></I><I> control</I></TD>
</TR>
<TR><TD  ALIGN=left NOWRAP><TT>set</TT></TD>
<TD  ALIGN=left NOWRAP><I>control </I><I>-&gt;</I><I> unit</I></TD>
</TR></TABLE>
</DIV>
<BR>
<DIV ALIGN=center>Figure 9.13: Control and statistical functions for the heap.</DIV><BR>

<A NAME="fig-statctrl"></A>
<DIV ALIGN=center><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE><A NAME="@fonctions330"></A><A NAME="@fonctions331"></A><A NAME="@fonctions332"></A><A NAME="@fonctions333"></A>The following functions, of type <I>unit -&gt; unit</I>, force the
execution of one or more stages of the Objective CAML garbage collector:
<TT>minor</TT> (stage 1), <TT>major</TT> (stages 1
and&nbsp;2), <TT>full_major</TT> (stages 1, 2 and&nbsp;3) and
<TT>compact</TT> (stages 1, 2, 3 and&nbsp;4).<BR>
<BR>

<H4> Examples</H4>
Here is what the <TT>Gc.stat</TT> call shows:


<PRE><BR># Gc.stat();;<BR><CODE>- : Gc.stat =</CODE><BR><CODE>{Gc.minor_words=549290; Gc.promoted_words=60620; Gc.major_words=204615;</CODE><BR><CODE> Gc.minor_collections=17; Gc.major_collections=2; Gc.heap_words=190464;</CODE><BR><CODE> Gc.heap_chunks=3; Gc.live_words=52727; Gc.live_blocks=12959;</CODE><BR><CODE> Gc.free_words=31155; Gc.free_blocks=84; Gc.largest_free=17899;</CODE><BR><CODE> Gc.fragments=3; Gc.compactions=0}</CODE><BR>

</PRE>
<BR>
<BR>
We see the number of executions of each phase: minor garbage collection,
major garbage collection, compaction, as well as the number of
words handled by the different memory spaces.
Calling <TT>compact</TT> forces the four stages of the garbage
collector, causing the heap statistics to be modified (see the call of <TT>Gc.stat</TT>).


<PRE><BR># Gc.compact();;<BR><CODE>- : unit = ()</CODE><BR># Gc.stat();;<BR><CODE>- : Gc.stat =</CODE><BR><CODE>{Gc.minor_words=555758; Gc.promoted_words=61651; Gc.major_words=205646;</CODE><BR><CODE> Gc.minor_collections=18; Gc.major_collections=4; Gc.heap_words=190464;</CODE><BR><CODE> Gc.heap_chunks=3; Gc.live_words=130637; Gc.live_blocks=30770;</CODE><BR><CODE> Gc.free_words=59827; Gc.free_blocks=1; Gc.largest_free=59827;</CODE><BR><CODE> Gc.fragments=0; Gc.compactions=1}</CODE><BR>

</PRE>
<BR>
<BR>
The fields <TT>GC.minor_collections</TT> and <TT>compactions</TT> are
incremented by&nbsp;1, whereas the field <TT>Gc.major_collections</TT> is
incremented by&nbsp;2. All of the fields of type <I>GC.control</I> are
modifiable. For them to be taken into account, we must use the
function <TT>Gc.set</TT>, which takes a value of type <I>control</I>
and modifies the behavior of the garbage collector.<BR>
<BR>
For example, the field <TT>verbose</TT> may take a value from 0 to
127, controlling 7 different indicators.


<PRE><BR># c<CODE>.</CODE>Gc.verbose<CODE> </CODE><CODE>&lt;-</CODE><CODE> </CODE><CODE>3</CODE><CODE>1</CODE>;;<BR><CODE>Characters 1-2:</CODE><BR><CODE>This expression has type int * int but is here used with type Gc.control</CODE><BR># Gc.set<CODE> </CODE>c;;<BR><CODE>Characters 7-8:</CODE><BR><CODE>This expression has type int * int but is here used with type Gc.control</CODE><BR># Gc.compact();;<BR><CODE>- : unit = ()</CODE><BR>

</PRE>

<BR>
<BR>
which prints:
<PRE>
&lt;&gt;Starting new major GC cycle
allocated_words = 329
extra_heap_memory = 0u
amount of work to do = 3285u
Marking 1274 words
!Starting new major GC cycle
Compacting heap...
done.
</PRE>The different phases of the garbage collector are indicated as well as
the number of objects processed.<BR>
<BR>
<HR>
<A HREF="book-ora087.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<A HREF="book-ora089.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
